5.3.1 Inserting New Items

To add a new todo item to a category, type i, which is bound to the command todo-insert-item.

i

This command is the entry point for inserting new items into a category (todo-insert-item). It prompts for additional keys until reaching a complete key sequence, which specifies the insertion parameters you wish to apply (see below). It then prompts for the text of the item, which you enter in the minibuffer.⁶ Called with one prefix argument, it also prompts for a category, and called with two prefix arguments, it prompts for both a file and a category from that file, and inserts the item accordingly; category name completion works as with the navigation command j. Finally, it inserts the item into the current or selected category of the current or selected todo file at the position in the list corresponding to the priority you choose, which also depends on the insertion parameters.

The name of this command reflects the fact that you can insert a new item into the category at any position, giving each new item any priority in the list, whereas speaking of adding an item to a category suggests appending it to the top or bottom.

In addition to its file and category, each newly inserted todo item has a priority in the category and begins with a header string, which includes at least the current date in the same format used by diary-insert-entry (see (emacs)Date Formats). You can specify the priority and the content of the header string in two ways. First, you can set the following item insertion options, which apply on every invocation of todo-insert-item.

• todo-default-priority is for automatically assigning a new item the highest or lowest priority in the category, if you do not explicitly assign it a priority on invoking todo-insert-item. By default, such new items are given highest priority, i.e., inserted at the top of the list.
• todo-always-add-time-string is for including or omitting the current time in the new item’s header. By default, this time string is omitted.
• todo-include-in-diary is for specifying whether the item appears in the Fancy Diary display (when the todo file is included in the Emacs diary file) by adding or omitting todo-nondiary-marker. By default, new todo items are so marked, thus excluded from the diary.
• todo-diary-nonmarking is for adding or omitting diary-nonmarking-symbol to items displayed in the diary, to control whether they are marked in the calendar (see (emacs)Format of Diary File). By default, todo items that are diary entries lack this symbol, thus are marked in the calendar.

Beside setting these options, for more flexibility you can also pass certain parameters on each invocation of todo-insert-item. These parameters concern not only the new item’s priority and header, but also its textual content. You pass these parameters by typing a sequence of one or more keys after the initial i.

Here is a list of the item insertion parameters together with their mnemonically associated keys⁷ and descriptions of their effect in todo-insert-item:

1. ‘default’ (i): Prompt for the new item’s priority (a number between 1 and one more than the number of items already in the category) and add a header string conforming to the values of the above options.

   ‘copy’ (p): Make an exact copy of the item at point, including its header string, and prompt for its priority. (This is useful for quickly making a new todo item whose text or header you want to differ only partly from that of an existing item: after inserting the copy, you can quickly edit it as needed by using operations described in the next section.)

2. ‘diary’ (y): Override the option todo-include-in-diary; that is, add todo-nondiary-marker if the option is non-nil, omit this marker if the option is nil.

   ‘nonmarking’ (k): Override the option todo-diary-nonmarking; that is, add diary-nonmarking-symbol if the option is non-nil, omit this symbol if the option is nil. Since this symbol only applies to diary items, the new item is automatically marked as such, i.e., lacks todo-nondiary-marker.

3. ‘calendar’ (c): Pop up the Emacs calendar and click a date in it to use that date in the new todo item’s header.

   ‘date’ (d): Prompt for entering in the minibuffer the year, month (with completion) and day number components of the header.

   ‘dayname’ (n): Prompt for entering in the minibuffer a weekday name as the date header instead of a year-month-day string.

4. ‘time’ (t): Prompt for entering a time string in the minibuffer instead of automatically inserting the current time; however, typing RET at the prompt enters the current time if todo-always-add-time-string is non-nil, otherwise it enters the empty string (i.e., no time string).
5. ‘here’ (h): Insert the new item in the position of the item at point, pushing that and all lower items in the category down, i.e., lowering their priority, by one.

   ‘region’ (r): Use the text of the selected region as the text of the new item, and insert this in accordance with the item insertion options and other parameters passed. If the option todo-use-only-highlighted-region is non-nil, then use the region only when it is highlighted; otherwise, use the region regardless of highlighting.

Note that the parameters are divided into five numbered groups; within a group, the parameters are mutually exclusive. Hence, to build a complete insertion operation, you select at most one parameter from at least one of these groups, by typing the corresponding key. If you want to apply more than one parameter, you must type the corresponding keys in the order of the numbered groups, subject to the following constraints.

The keys of groups 2-4 are continuation keys, that is, each can be followed by a key from a following group. If you want to finish the sequence with a continuation key, you must double the final key. For example, i y is not a complete key sequence; rather, you must type i y y.

By contrast, the keys of groups 1 and 5 are final keys; for example, i i and i h are complete sequences. The reason for making two separate groups of the final keys is that the parameters ‘default’ and ‘copy’ cannot be combined with any other parameters, while ‘here’ and ‘region’ can be combined with any of the parameters from groups 2-4.

To aid you in building item insertion key sequences, when you type an insertion key, this displays a prompt in the echo area showing pairs of the remaining possible keys and their associated parameters, grouped and ordered in accordance with the above list. The initial prompt, after typing i to invoke todo-insert-item, looks like this:

Press a key (so far i):  { i=>default p=>copy } { y=>diary k=>nonmarking } { c=>calendar d=>date n=>dayname } t=>time { h=>here r=>region }

If you now type y, the prompt changes to this:

Press a key (so far i y):  y=>diary:GO! { c=>calendar d=>date n=>dayname } t=>time { h=>here r=>region }

Notice that the pair ‘k=>nonmarking’ is now absent, since it belongs to the same group as the selected pair ‘y=>diary’, hence is no longer available for this sequence. Since y is a continuation key, it is still available, but now the string ‘:GO!’ is appended to the pair to remind you that pressing this key again will complete the sequence.

An alternative to the key sequence i c c for choosing the item’s date from the calendar is also available: when point is already on a date in the calendar, typing i t (todo-insert-item-from-calendar) prompts for a new item and its priority and inserts it in the current category. This command, like todo-insert-item, also accepts one or two prefix arguments for choosing the category via minibuffer completion. Note, however, that the key sequence i t is not defined in Todo mode but in the Calendar mode keymap. It is a convenient shortcut if you happen to be using the calendar when you decide to make a new todo item. (Contrast this with passing the ‘calendar’ parameter, which pops open the calendar after you have entered the item’s text, and then you can choose a date from the calendar.)